home *** CD-ROM | disk | FTP | other *** search
/ Skunkware 5 / Skunkware 5.iso / man / cat.3 / AddErrInfo.3 < prev    next >
Text File  |  1995-07-25  |  12KB  |  199 lines
  1.  
  2.  
  3.  
  4.      TTTTccccllll____AAAAddddddddEEEErrrrrrrroooorrrrIIIInnnnffffoooo((((3333))))          TTTTccccllll (((( ))))          TTTTccccllll____AAAAddddddddEEEErrrrrrrroooorrrrIIIInnnnffffoooo((((3333))))
  5.  
  6.  
  7.  
  8.      _________________________________________________________________
  9.  
  10.      NNNNAAAAMMMMEEEE
  11.           Tcl_AddErrorInfo, Tcl_SetErrorCode, Tcl_PosixError -  record
  12.           information about errors
  13.  
  14.      SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  15.           ####iiiinnnncccclllluuuuddddeeee <<<<ttttccccllll....hhhh>>>>
  16.  
  17.           TTTTccccllll____AAAAddddddddEEEErrrrrrrroooorrrrIIIInnnnffffoooo(_i_n_t_e_r_p, _m_e_s_s_a_g_e)
  18.  
  19.           TTTTccccllll____SSSSeeeettttEEEErrrrrrrroooorrrrCCCCooooddddeeee(_i_n_t_e_r_p, _e_l_e_m_e_n_t, _e_l_e_m_e_n_t, ... ((((cccchhhhaaaarrrr ****)))) NNNNUUUULLLLLLLL)
  20.  
  21.           char *
  22.           TTTTccccllll____PPPPoooossssiiiixxxxEEEErrrrrrrroooorrrr(_i_n_t_e_r_p)
  23.  
  24.      AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
  25.           Tcl_Interp   *_i_n_t_e_r_p    (in)      Interpreter  in  which  to
  26.                                             record information.
  27.  
  28.           char         *_m_e_s_s_a_g_e   (in)      Identifying   string    to
  29.                                             record     in    eeeerrrrrrrroooorrrrIIIInnnnffffoooo
  30.                                             variable.
  31.  
  32.           char         *_e_l_e_m_e_n_t   (in)      String to  record  as  one
  33.                                             element    of    eeeerrrrrrrroooorrrrCCCCooooddddeeee
  34.                                             variable.   Last   _e_l_e_m_e_n_t
  35.                                             argument must be NULL.
  36.      _________________________________________________________________
  37.  
  38.  
  39.      DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  40.           These procedures are used to manipulate two global variables
  41.           that  hold information about errors.  The variable eeeerrrrrrrroooorrrrIIIInnnnffffoooo
  42.           holds a stack trace of the operations that were in  progress
  43.           when  an  error  occurred,  and  is  intended  to  be human-
  44.           readable.  The variable eeeerrrrrrrroooorrrrCCCCooooddddeeee holds a list of items that
  45.           are  intended  to  be  machine-readable.   The first item in
  46.           eeeerrrrrrrroooorrrrCCCCooooddddeeee identifies the class of error that occurred  (e.g.  |
  47.           POSIX  means  an  error occurred in a POSIX system call) and
  48.           additional elements in eeeerrrrrrrroooorrrrCCCCooooddddeeee hold additional  pieces  of
  49.           information  that depend on the class.  See the Tcl overview
  50.           manual  entry  for  details  on  the  various  formats   for
  51.           eeeerrrrrrrroooorrrrCCCCooooddddeeee.
  52.  
  53.           The eeeerrrrrrrroooorrrrIIIInnnnffffoooo variable is gradually built  up  as  an  error
  54.           unwinds  through  the nested operations.  Each time an error
  55.           code  is  returned  to  TTTTccccllll____EEEEvvvvaaaallll  it  calls  the   procedure
  56.           TTTTccccllll____AAAAddddddddEEEErrrrrrrroooorrrrIIIInnnnffffoooo   to   add  additional  text  to  eeeerrrrrrrroooorrrrIIIInnnnffffoooo
  57.           describing the command that  was  being  executed  when  the
  58.           error  occurred.   By the time the error has been passed all
  59.           the way back to the application, it will contain a  complete
  60.  
  61.  
  62.  
  63.      Page 1                                          (printed 7/10/95)
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.      TTTTccccllll____AAAAddddddddEEEErrrrrrrroooorrrrIIIInnnnffffoooo((((3333))))          TTTTccccllll (((( ))))          TTTTccccllll____AAAAddddddddEEEErrrrrrrroooorrrrIIIInnnnffffoooo((((3333))))
  71.  
  72.  
  73.  
  74.           trace of the activity in progress when the error occurred.
  75.  
  76.           It is sometimes useful  to  add  additional  information  to
  77.           eeeerrrrrrrroooorrrrIIIInnnnffffoooo  beyond  what  can  be  supplied  automatically by
  78.           TTTTccccllll____EEEEvvvvaaaallll.  TTTTccccllll____AAAAddddddddEEEErrrrrrrroooorrrrIIIInnnnffffoooo may be used  for  this  purpose:
  79.           its  _m_e_s_s_a_g_e  argument  contains  an additional string to be
  80.           appended to eeeerrrrrrrroooorrrrIIIInnnnffffoooo.   For  example,  the  ssssoooouuuurrrrcccceeee  command
  81.           calls  TTTTccccllll____AAAAddddddddEEEErrrrrrrroooorrrrIIIInnnnffffoooo to record the name of the file being
  82.           processed and the line number on which the  error  occurred;
  83.           for  Tcl  procedures,  the  procedure  name  and line number
  84.           within the procedure are recorded, and so on.  The best time
  85.           to call TTTTccccllll____AAAAddddddddEEEErrrrrrrroooorrrrIIIInnnnffffoooo is just after TTTTccccllll____EEEEvvvvaaaallll has returned
  86.           TTTTCCCCLLLL____EEEERRRRRRRROOOORRRR.  In calling TTTTccccllll____AAAAddddddddEEEErrrrrrrroooorrrrIIIInnnnffffoooo,  you  may  find  it
  87.           useful  to  use  the eeeerrrrrrrroooorrrrLLLLiiiinnnneeee field of the interpreter (see
  88.           the TTTTccccllll____IIIInnnntttteeeerrrrpppp manual entry for details).
  89.  
  90.           The procedure TTTTccccllll____SSSSeeeettttEEEErrrrrrrroooorrrrCCCCooooddddeeee is used to set the  eeeerrrrrrrroooorrrrCCCCooooddddeeee
  91.           variable.  Its _e_l_e_m_e_n_t arguments give one or more strings to
  92.           record in eeeerrrrrrrroooorrrrCCCCooooddddeeee:  each _e_l_e_m_e_n_t will become one item of a
  93.           properly-formed    Tcl    list    stored    in    eeeerrrrrrrroooorrrrCCCCooooddddeeee.
  94.           TTTTccccllll____SSSSeeeettttEEEErrrrrrrroooorrrrCCCCooooddddeeee is typically invoked just before  returning
  95.           an   error.    If  an  error  is  returned  without  calling
  96.           TTTTccccllll____SSSSeeeettttEEEErrrrrrrroooorrrrCCCCooooddddeeee then the Tcl interpreter automatically sets
  97.           eeeerrrrrrrroooorrrrCCCCooooddddeeee to NNNNOOOONNNNEEEE.
  98.  
  99.           TTTTccccllll____PPPPoooossssiiiixxxxEEEErrrrrrrroooorrrr sets the eeeerrrrrrrroooorrrrCCCCooooddddeeee variable after an error in  |
  100.           a  POSIX  kernel  call.   It  reads the value of the eeeerrrrrrrrnnnnoooo C  |
  101.           variable and calls TTTTccccllll____SSSSeeeettttEEEErrrrrrrroooorrrrCCCCooooddddeeee to set eeeerrrrrrrroooorrrrCCCCooooddddeeee in  the  |
  102.           PPPPOOOOSSSSIIIIXXXX  format.  In addition, TTTTccccllll____PPPPoooossssiiiixxxxEEEErrrrrrrroooorrrr returns a human-  |
  103.           readable diagnostic message for the error (this is the  same
  104.           value  that  will appear as the third element in eeeerrrrrrrroooorrrrCCCCooooddddeeee).
  105.           It may be convenient to include this string as part  of  the
  106.           error message returned to the application in _i_n_t_e_r_p->_r_e_s_u_l_t.
  107.  
  108.           It is important to call the procedures described here rather
  109.           than   setting   eeeerrrrrrrroooorrrrIIIInnnnffffoooo   or   eeeerrrrrrrroooorrrrCCCCooooddddeeee   directly  with
  110.           TTTTccccllll____SSSSeeeettttVVVVaaaarrrr.  The reason for this is that the Tcl interpreter
  111.           keeps  information  about whether these procedures have been
  112.           called.  For example, the  first  time  TTTTccccllll____AAAAppppppppeeeennnnddddRRRReeeessssuuuulllltttt  is
  113.           called  for  an  error,  it  clears  the  existing  value of
  114.           eeeerrrrrrrroooorrrrIIIInnnnffffoooo and adds the error message  in  _i_n_t_e_r_p->_r_e_s_u_l_t  to
  115.           the variable before appending _m_e_s_s_a_g_e;  in subsequent calls,
  116.           it just appends the new _m_e_s_s_a_g_e.  When  TTTTccccllll____SSSSeeeettttEEEErrrrrrrroooorrrrCCCCooooddddeeee  is
  117.           called,  it  sets  a flag indicating that eeeerrrrrrrroooorrrrCCCCooooddddeeee has been
  118.           set;  this allows the Tcl interpreter to  set  eeeerrrrrrrroooorrrrCCCCooooddddeeee  to
  119.           NNNNOOOONNNNEEEE  iiiiffff  iiiitttt  rrrreeeecccceeeeiiiivvvveeeessss aaaannnn eeeerrrrrrrroooorrrr rrrreeeettttuuuurrrrnnnn wwwwhhhheeeennnn TTTTccccllll____SSSSeeeettttEEEErrrrrrrroooorrrrCCCCooooddddeeee
  120.           hasn't been called.
  121.  
  122.           If the procedure TTTTccccllll____RRRReeeesssseeeettttRRRReeeessssuuuulllltttt is called, it clears all of
  123.           the  state  associated  with eeeerrrrrrrroooorrrrIIIInnnnffffoooo and eeeerrrrrrrroooorrrrCCCCooooddddeeee (but it
  124.           doesn't actually modify the variables).   If  an  error  had
  125.           occurred,  this will clear the error state to make it appear
  126.  
  127.  
  128.  
  129.      Page 2                                          (printed 7/10/95)
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.      TTTTccccllll____AAAAddddddddEEEErrrrrrrroooorrrrIIIInnnnffffoooo((((3333))))          TTTTccccllll (((( ))))          TTTTccccllll____AAAAddddddddEEEErrrrrrrroooorrrrIIIInnnnffffoooo((((3333))))
  137.  
  138.  
  139.  
  140.           as if no error had occurred after all.
  141.  
  142.  
  143.      SSSSEEEEEEEE AAAALLLLSSSSOOOO
  144.           Tcl_ResetResult, Tcl_Interp
  145.  
  146.  
  147.      KKKKEEEEYYYYWWWWOOOORRRRDDDDSSSS
  148.           error, stack, trace, variable
  149.  
  150.  
  151.  
  152.  
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.      Page 3                                          (printed 7/10/95)
  196.  
  197.  
  198.  
  199.